home *** CD-ROM | disk | FTP | other *** search
/ SGI Developer Toolbox 6.1 / SGI Developer Toolbox 6.1 - Disc 1.iso / toolbox / src / exampleCode / opengl / oat / README < prev    next >
Text File  |  1996-11-11  |  8KB  |  207 lines
  1.  
  2.              ~4Dgifts/toolbox/src/exampleCode/opengl/oat README
  3.  
  4.  
  5.                            OpenGL Attribute Tester
  6.                            =======================
  7.  
  8.  
  9. 'oat' (OpenGL Attribute Tester) is a program for testing the functionality
  10. of OpenGL on different platforms.
  11.  
  12. UNFORTUNATELY,  we were unsuccessful in recompiling oat on IRIX 6.2.
  13.  
  14.                 However, pursuing our goal of extending collaboration 
  15.                 between the DTjanitor and everyone in the Developer Program, 
  16.                 although we were not able to port/successfully recompile 
  17.                 this source to/on IRIX 6.2, we still include all files 
  18.                 so that, if any one of you has the saavy, and finds 
  19.                 the inclination/motivation enabling you to succeed in 
  20.                 reviving oat, PLEEZE send us whatever files (source, 
  21.                 Makefile, etc.) you modify to "make it go" again, and 
  22.                 we will add these back into the v6.2 DT release as 
  23.                 resuscitated src+binaries. 
  24.  
  25.  
  26.  
  27. It provides a GUI interface to test most (hopefully all) the different
  28. attributes that are changeable in OpenGL.
  29.  
  30. run it as:
  31.  
  32. oat [<filemame>]
  33.  
  34. where <filename> is an Inventor .iv data file.  In the iv subdir you'll 
  35. find some test files, like cone.iv, sphere.iv, tri.iv (triangle), 
  36. plane.iv (a quad), etc.
  37.  
  38. Also, the /usr/demos/data/yaodl/*.ydl files have been converted into .iv 
  39. format and you can find them in 
  40. /hosts/mistral.esd/usr/people/kyriazis/oat/bin/iv, if you are internal to SGI.
  41.  
  42. This program uses the Inventor interaction paradigm, so if you are
  43. unfamiliar with it, go learn it! :-)  Actually, play around with ivview
  44. to get accustomed to it.
  45.  
  46. This program is not meant to be an Inventor file viewer, but a tester for
  47. OpenGL attributes, etc., so all attributes that your .iv file contains
  48. are being stripped out, hopefully in a graceful manner.  Also, some Inventor
  49. primitives are not supported, because I had to alter them to get rid of
  50. any interaction that Inventor has with OpenGL.  Namely, the only primitives
  51. that are supported are: Cone, Cylinder, Sphere, Cube, FaceSet and 
  52. IndexedFaceSet.
  53.  
  54. In addition, when oat starts up it uses the initial OpenGL defaults, which
  55. are not necesserily visually pleasing:  No lighting, no shading, everything
  56. is a dull white.  But, again, oat is supposed to test OpenGL, so it starts
  57. up by setting no OpenGL attributes whatsoever.
  58.  
  59.  
  60. Command-Line Options
  61. --------------------
  62.  
  63. They go before the filename.  Current ones are:
  64.  
  65. -ci    Start up in a Color Index visual.
  66.  
  67. -sb    Start up in a single-buffer mode (instead of double buffer if
  68.     that exists).
  69.  
  70. -nr    Disable quick interaction.  By default, everything you change
  71.     (through the GUI) triggers a redraw.  This frag disables this
  72.     behavior, so you can change multiple parameters at the same time,
  73.     and then redraw the scene manually.
  74.  
  75. -fps    Print (to stdout) frames per second after each frame.  It is
  76.     calculated as 1 / seconds-per-frame.
  77.  
  78. -h    Displays a help screen.
  79.  
  80.  
  81. User Interface:
  82. ---------------
  83.  
  84. There are several menus and popup panels that are available.  We will go
  85. through them as they appear in the menubar.
  86.  
  87. FILE:
  88.   Open:        Open an .iv file
  89.   Quit:        Quit oat
  90.  
  91. Manips:        Selects an Inventor SoTransformManip to be used when
  92.         using the pointer (from the panel on the right).
  93.     
  94. POPUPS:        These are the popup panels that allow you to alter OpenGL
  95.         attribute.  Classification was done more-or-less according
  96.         to "The OpenGL Machine" poster.
  97.  
  98. VIEW:        Setup ortho or perspective view.
  99.  
  100. VISUALS:    Choose an X visual to be used..  The menu contains a list of
  101.         all the visuals of the X server that support OpenGL rendering,
  102.         in order words, all the visuals that that you can use in
  103.         the current graphics hardware.
  104.  
  105.  
  106. One thing which is a bit non-obvious is that for one-line text item, you
  107. let the program know you are done by pressing your average Return key.
  108. For multi-line text items, you use the ENTER key at the far right of the
  109. keyboard..  (It was a Motif-ism...  If you find an easy way to solve this
  110. problem, change TextItem.* and MatrixItem.*).
  111.  
  112. There is also a column of buttons on the right of the drawing area.
  113. These buttons are almost identical to the buttons existing in SceneViewer.
  114. Here is a brief description:
  115.  
  116. Arrow/Hand:    Pick/Move toggles.
  117.  
  118. House:        Go Home
  119.  
  120. House w/ arrow:    Set Home position.
  121.  
  122. Weird eye:    Alter the view so that the BBox of the scene fits in view.
  123.  
  124. Target:        Smooth motion to picked point.
  125.  
  126. PIXMAP:        Create a pixmap using current visual, draw in it, dump it in
  127.         an RGB file, and then display that file using ipaste.
  128.  
  129.  
  130. IMPLEMENTATION:
  131.  
  132. This program was written using C++, Inventor, and ViewKit.  I attempted
  133. to structure code as much as possible, so it should be relatively easy
  134. to alter or add functionality.  Look at src/Makefile for a brief
  135. classification of the files.
  136.  
  137. GlWindow is the main "dispatcher" class that figures out what to do with
  138. each user event.  Unfortunately, it's a pretty monilithic class, and I
  139. haven't bothered myself with finding an easy way of splitting it up. If
  140. you find an easy way, please let me know.
  141.  
  142. There is one class for each of the user-interface panels that show up.
  143. The user interface is created automatically in an algorithmic manner.  That's
  144. why the layout my look a bit stupid.  The superclass (IfaceGenerator) of
  145. the interface classes provides the parser that reads in the description
  146. of the window and creates the Motif widgets.  There is a wrapper around
  147. each one of the OpenGL functions in order to provide an easy way to 
  148. provide feedback debugging information.  Additionally, each user interface
  149. class has a local mirror of the part of the OpenGL state that it alters, so
  150. that it can keep OpenGL in sync with the user interface when visuals are
  151. changed, etc.
  152.  
  153. Inventor is used for primitive description and database traversal.  Since
  154. Inventor does a lot of attribute binding behind our backs, I copied the
  155. most significant parts of the GLRender routines of certain SoShapes and
  156. made local copies of those primitives that do not alter the state.  In this
  157. way, Oat has full control of the OpenGL state.  Instances of the those
  158. local classes are created when an Inventor file is read in.  After an
  159. Inventor file is being loaded in, it is being traversed to check if it
  160. contains any shape nodes that are not "converted", or any attribute nodes.
  161. Such nodes are then erased from the tree.
  162.  
  163. This program uses X application default files.  By default "make install"
  164. put the defaults file (called Oat) into $ROOT/usr/lib/X11/app-defaults.
  165. You should make arrangements of being able to have that directory in your 
  166. XAPPLRESDIR or XUSERFILESEARCHPATH, otherwise your user interface may
  167. pop up in that ugly default Motif blue color with the very ugly buttons.
  168.  
  169.  
  170.  
  171. Also, for your convenience, the parent directory has a file called
  172. "stipple-pats".  This contains sample stipple patterns to be used with
  173. the polygon stipple text item.  In order to use one of them, empty out
  174. the polygon stipple text area, 'cat' the stipple-pats file in a separate
  175. window, highlight the pattern you want (with the left mouse button), and
  176. paste it in the stipple text area (with the middle button).  Don't forget
  177. to confirm your selection with ENTER (not Return;  this is a multi-line
  178. text item).
  179.  
  180.  
  181.  
  182. USER-DEFINED PRIMITIVES:
  183.  
  184. I have made a subclass of Inventor's SoShape node, which allows the person
  185. who plays around with 'oat', to add his own OpenGL code in the GlUserDef1
  186. class and test some obscure OpenGL case, that way.
  187.  
  188. You can make a .iv file that contains an instance of UserDef1, and load the
  189. file as you would normally.
  190.  
  191. If you'd like to play around with that file, look in GlUserDef1.* for code
  192. that has been #ifdef'ed out like:
  193.  
  194. #ifdef FILL_HERE
  195. ..
  196. ..
  197. #endif
  198.  
  199. It should be more or less obvious...
  200.  
  201.  
  202.  
  203. If you have any questions, please send mail to kyriazis@sgi.com
  204.  
  205. George Kyriazis
  206. kyriazis@sgi.com
  207.